PTV Drive&Arrive | API Guide > API Description > /tour/_POST

Tour

/tour POST - Create a tour (relevant to billing)

For legacy Tour POST API see the section below.

This function is called with https://driveandarrive-v1.cloud.ptvgroup.com/em/tour?token=<your-token>&source=<myProduct_Vx.y>. Every successful function call leads to a transaction count in the billing system. Every transaction is charged according to your agreements with PTV Group.

Parameters:

token: identifies the customer of PTV Drive&Arrive
source: optional, arbitrary text to identify the component which creates a tour

Payload:

"tour": a JSON object describing a trip. The structure of the JSON object is:

field	type	suggested length/ format	mandatory	description
stops	array		x	a list of stops of this trip
stops[i].coordinate.locationX	double	[-]##0.#######	x	longitude of coordinate in WGS 84, e.g. 13.4261419 for Berlin
stops[i].coordinate.locationY	double	[-]##0.#######	x	latitude of coordinate in WGS 84, e.g. 52.5075419 for Berlin
stops[i].earliestArrivalTime	string	YYYY-MM-DDThh:mm:ss.0000000+hh:mm		start of time window at the specific stop
stops[i].latestDepartureTime	string	YYYY-MM-DDThh:mm:ss.0000000+hh:mm		end of time window at the specific stop
stops[i].pta	string	YYYY-MM-DDThh:mm:ss.0000000+hh:mm		planned time of arrival - for informative purpose only
stops[i].serviceTimeAtStop	integer			service time at stop in seconds
stops[i].useServicePeriodForRecreation	boolean			"true" if service time can be used as rest time, otherwise "false"
stops[i].weightWhenLeavingStop	integer			truck weight when leaving stop in kg
stops[i].locationId	string			ID of the location to the stop
stops[i].Address	address			stop's address
stops[i].Address.label	string			address label - eg. Gate 1
stops[i].Address.country	string			address country
stops[i].Address.state	string			address state
stops[i].Address.province	string			address province
stops[i].Address.postcode	string			address postcode
stops[i].Address.city	string			address city
stops[i].Address.city2	string			address city district
stops[i].Address.street	string			address street
stops[i].Address.houseNumber	string			address house number
stops[i].useLocationAddress	bool			Use address from location if not provided here
stops[i].customData	object			a JSON object with arbitrary data
vehicle.vehicleProfileID	string	"mg-car", "mg-transporter", "mg-truck-7.5t", "mg-truck-11.99t", "mg-truck-40t", "mg-trailer-truck"	x	vehicle type driver is using. If the Token got the WORLD mapCLuster configured then the following vehicle profiles are available too: "1_pickup", "2_van", "3_walk_in", "4_box_truck", "5_delivery", "6_stake_body", "7_medium_tractor", "8_double_trailer", "8_heavy_tractor", "8_semitrailer_3Axle", "8_semitrailer_4Axle", "8_semitrailer_5Axle". For detailed information: Vehicle Profiles
vehicle.telematicData				Telematics provider information for pushing position events to D&A. For detailed information: Positions from Telematics Systems
vehicle.telematicData.provider	string		x	Telematics provider name
vehicle.telematicData.vehicleId	string		x	Vehicle license plate number known to provider
vehicle.telematicData.startTime	string	YYYY-MM-DDThh:mm:ss.0000000+hh:mm	x	Start time for pushing positions to tour
vehicle.telematicData.endTime	string	YYYY-MM-DDThh:mm:ss.0000000+hh:mm		End time for stopping push positions to tour. If not provided, end time will be calculated automatically with reference to the vehicle.telematicData.startTime.
drivers	array			array of drivers. Drive&Arrive currently supports only one driver element.
drivers[j].driverDescription	string			driver description
drivers[j].useRaSTime	boolean			consider break and rest in ETA calculations
drivers[j].raSTime	object			break and rest details
drivers[j].raSTime.periodDrivenSinceLastBreak	integer			amount of time the driver has spent operating his vehicle since the last break (in seconds)
drivers[j].raSTime.periodDrivenSinceLastRest	integer			amount of time the driver has spent operating his vehicle since the last rest (in seconds)
drivers[j].raSTime.currentIdlePeriod	integer			amount of time the driver has spent idle right before the reference time (in seconds)
drivers[j].raSTime.isSplitBreak	boolean			True if the driver has already completed the first part of his split break. Since then he has operated his vehicle or performed active service.
drivers[j].raSTime.isSplitRest	boolean			True if the driver has already completed the first part of his split rest. Since then he has operated his vehicle or performed active service.
drivers[j].customData	object			custom json object related to driver
customData	object			a JSON object with arbitrary data
options	options			Additional tour options
options.plannedTourStartTime	string	YYYY-MM-DDThh:mm:ss.0000000+hh:mm		Planned tour start date and time
options.doRefRouteCalc	boolean			True if a reference ETA is required for the tour. Stop 1 being the start point.

Following validation takes place on the tour payload:

At least 1 stop should be existing.
Missing EarliestArrivalTime or LatestDepartureTime, when only one of them is present.
EarliestArrivalTime should be earlier than LatestDepartureTime and serviceTime, if both existing.
Valid coordinates in each stop
Tour duration is checked against maximum allowed tour duration, if interval in the stops exists.

Example

Request

{
  "tour": {
    "stops": [
	  {
	    "coordinate": {
	      "locationX": 9.000000,
	      "locationY": 49.000000
	    },
	    "earliestArrivalTime": "YYYY-MM-DDThh:mm:ss.0000000+01:00",
	    "latestDepartureTime": "YYYY-MM-DDThh:mm:ss.0000000+01:00",
	    "pta": "YYYY-MM-DDThh:mm:ss.0000000+01:00",
	    "serviceTimeAtStop": 900,
	    "useServicePeriodForRecreation": true,
	    "weightWhenLeavingStop": 5000
	  },
	  {
	    "coordinate": {
	      "locationX": 8.000000,
	      "locationY": 49.000000
	    },
	    "address": {
	      "label": "Gate 5",
	      "street": "some street 45",
	      "city": "Karlsruhe"
	    },
	    "earliestArrivalTime": "YYYY-MM-DDThh:mm:ss.0000000+01:00",
	    "latestDepartureTime": "YYYY-MM-DDThh:mm:ss.0000000+01:00",
	    "pta": "YYYY-MM-DDThh:mm:ss.0000000+01:00",
	    "serviceTimeAtStop": 600,
	    "useServicePeriodForRecreation": true,
	    "weightWhenLeavingStop": 0,
	    "customData": {
	      "orderId": "23534579"
	    }
	  }
 	],
    "vehicle": {
	  "vehicleProfileID": "mg-truck-40t",
	  "telematicData": {                    // tour connect object
	    "provider": "gps_provider_name",    // telematics provider
	    "vehicleId": "XXYYZZ",              // vehicle license plate number
	    "startTime": "2017-03-28T00:00:00.0000000+00:00",
	    "endTime": "2017-03-31T00:00:00.0000000+00:00"						
	  }
    },
    "drivers": [
      {
        "driverDescription": "driver 1",
        "raSTime": {
          "periodDrivenSinceLastBreak": 0,
          "periodDrivenSinceLastRest": 0,
          "currentIdlePeriod": 0,
          "isSplitBreak": false,
          "isSplitRest": false
        },
        "useRaSTime": true
      }
    ],
    "customData": {
      "tripId": "example_0001"
    },
    "options": {
      "plannedTourStartTime": "YYYY-MM-DDThh:mm:ss.0000000+01:00",
      "doRefRouteCalc": true
    }
  }
}

Response

A success response is returned with the tour created on success. If not, one of the exception messages with its error code from below is returned.

Exceptions

validation / message	errorCode
The count of stops of a tour has to be between 1 and 100.	INVALID_STOP_COUNT
Stop have not any coordinates.	STOP_WITHOUT_COORDINATES
Stop has invalid coordinate format, WGS84 is expected.	STOP_WITH_INVALID_COORDINATES
latestDepartureTime of stop before earliestArrivalTime	TIME_OF_STOP_INVALID
Time of Stop is invalid.	TIME_OF_STOP_MISSING
Token does not exist.	TOKEN_ERROR
The validation date of the token is expired	TOKEN_EXPIRED
Not supported Token.Type used.	TOKEN_TYPE
Token is blocked. Please contact support in order to get further information	TOKEN_BLOCKED
The number of tours that are allowed for the token is reached. Please ask your sales contact for further information.	TOKEN_TOUR_LIMIT_REACHED
In a tour with 2 stops, the stop coordinates needs to be different.	2_STOP_TOUR_REQUIRES_DIFF_COORDINATES
Tour start cannot be N days in the future. [START_TIME]	INVALID_TOUR_START_DATETIME
Maximum allowed tour duration of N days from [TOUR_DURATION] has been exceeded.	TOUR_DURATION_EXCEEDED

Start time and tour duration

For these parameters a default of 7 days is used, but it is possible to customize these limits per call which is identified via access token.

Reference Route

A reference route for the tour is calculated automatically if date and time information is available either for tour start or the first stop of the tour. This can be disabled with the doRefRouteCalc option set to false in the tour options.

Tour Connect (positions from telematics provider)

To receive positions from a known telematics provider, a TelematicData object should be supplied in the vehicle. Only tours with a valid tour connect can accept position events with Tour SCEMID.

Good to know: Positions from Telematics Systems

Sending position events with Tour SCEMID is an experimental feature for tours with multiple stops.

Tour Connect Exception

validation / message	errorCode
Vehicle Id is required for telematics.	TELEMATIC_VEHICLEID_REQUIRED
Telematics provider name should not be empty.	TELEMATIC_PROVIDER_EMPTY_OR_MISSING
Start time for telematics positions is required.	TELEMATIC_STARTTIME_REQUIRED

/tour/batch/ GET - read multiple tours which belongs to the specified SCEM-IDs

This function is called with https://driveandarrive-v1.cloud.ptvgroup.com/em/tour/batch?token=<token>&SCEMIDS=<SCEMID[,SCEMID]>&source=<myProduct_Vx.y>

Result

{
  "tours": [
    {
      "stops": [
        {
          "coordinate": {
            "locationX": 9.000000,
            "locationY": 48.000000
          },
          "earliestArrivalTime": "YYYY-MM-DDThh:mm:ss.0000000+01:00",
          "latestDepartureTime": "YYYY-MM-DDThh:mm:ss.0000000+01:00",
          "pta": "YYYY-MM-DDThh:mm:ss.0000000+01:00",
          "serviceTimeAtStop": 900,
          "useServicePeriodForRecreation": true,
          "weightWhenLeavingStop": 5000,
          "customData": {
            
          },
          "scemid": "X1X1X1X1X1"
        },
        {
          "coordinate": {
            "locationX": 8.0,
            "locationY": 49.0
          },
          "earliestArrivalTime": "YYYY-MM-DDThh:mm:ss.0000000+01:00",
          "latestDepartureTime": "YYYY-MM-DDThh:mm:ss.0000000+01:00",
          "pta": "YYYY-MM-DDThh:mm:ss.0000000+01:00",
          "serviceTimeAtStop": 600,
          "useServicePeriodForRecreation": true,
          "weightWhenLeavingStop": 0,
          "customData": {
            "orderId": "23534579"
          },
          "scemid": "X2X2X2X2X2"
        }
      ],
      "vehicle": {
        "vehicleProfileID": "mg-truck-40t"
      },
      "drivers": [
        {
          "driverDescription": "driver2",
          "raSTime": {
            "periodDrivenSinceLastBreak": 0,
            "periodDrivenSinceLastRest": 0,
            "currentIdlePeriod": 0,
            "isSplitBreak": false,
            "isSplitRest": false
          },
          "useRaSTime": true
        }
      ],
      "customData": {
        "tripId": "example_0001"
      },
      "scemid": "X9X9X9X9X9"
    }
  ],
  "responseStatus": {
    "errorCode": "SUCCESS",
    "message": "000000000000"
  }
}

Exceptions

validation / message	errorCode
Token does not exist.	TOKEN_ERROR
SCEM-ID not valid. SCEM-ID should be a 10-digit, case-sensitive, alphanumeric identifier of an existing tour.	SCEMID_INVALID
Reading of multiple tours is not allowed.	ERR_MESSAGE_INVALID_READ_TOUR_COUNT

/tour/batch/ PUT - update multiple tours which belong to the specified SCEM-IDs

Updating a single stop can be done via https://driveandarrive-v1.cloud.ptvgroup.com/em/stop/batch/?token=<token>&source=<myProduct_Vx.y> PUT - but if there is a system that manages a complete tour and allows multiple changes it would be difficult to track all updates even if there are not many. The call https://driveandarrive-v1.cloud.ptvgroup.com/em/tour/batch/?token=token=<token>&source=<myProduct_Vx.y> PUT allows the entire exchange of currently only one existing tour.

If a SCEMID is missing the corresponding stop will be removed from the entire trip.
In order to change data of existing stops the SCEMID of this stop must be transmitted.
To add a new stop no SCEMID for this stop has to be transferred.
stopPositionInTour could be used for client side ordering. It is not verified whether stopPositionInTour is unique etc. internally
rest and service times relates to first stop

Parameters:

token: identifies the customer of PTV Drive&Arrive
source: optional, arbitrary text to identify the component which created the location

Payload:

"tours": a JSON object describing multiple trips. The structure of the JSON object is:

field	type	suggested length/ format	mandatory	description
stops	string		x	a list of stops of this trip
stops[i].coordinate.locationX	double	[-]##0.#######	x	longitude of coordinate in WGS 84, e.g. 13.4261419 for Berlin
stops[i].coordinate.locationY	double	[-]##0.#######	x	latitude of coordinate in WGS 84, e.g. 52.5075419 for Berlin
stops[i].earliestArrivalTime	string	YYYY-MM-DDThh:mm:ss.0000000+hh:mm	x	start of time window at the specific stop
stops[i].latestDepartureTime	string	YYYY-MM-DDThh:mm:ss.0000000+hh:mm	x	end of time window at the specific stop
stops[i].pta	string	YYYY-MM-DDThh:mm:ss.0000000+hh:mm		planned time of arrival - for informative purpose only
stops[i].serviceTimeAtStop	integer		x	service time of driver X at stop in seconds
stops[i].useServicePeriodForRecreation	boolean		x	"true" if service time can be used as rest time, otherwise "false"
stops[i].weightWhenLeavingStop	integer		x	truck weight when leaving stop in kg
stops[i].locationId	string			ID of the location to the stop.
stops[i].Address	address			stop's address
stops[i].Address.label	string			address label - eg. Gate 1
stops[i].Address.country	string			address country
stops[i].Address.state	string			address state
stops[i].Address.province	string			address province
stops[i].Address.postcode	string			address postcode
stops[i].Address.city	string			address city
stops[i].Address.city2	string			address district
stops[i].Address.street	string			address street
stops[i].Address.houseNumber	string			address house number
stops[i].useLocationAddress	bool			Use address from location if not provided here.
stops[i].customData	object			a JSON object with arbitrary data
stops[i].scemid	string	^[0-9]{10}$		identifier of existing stop
vehicle.vehicleProfileID	string	"mg-car", "mg-transporter", "mg-truck-7.5t", "mg-truck-11.99t", "mg-truck-40t", "mg-trailer-truck"	x	vehicle type driver is using
vehicle.telematicData				Telematics provider information for pushing position events to D&A.
vehicle.telematicData.provider	string		x	Telematics provider name
vehicle.telematicData.vehicleId	string		x	Vehicle license plate number known to provider
vehicle.telematicData.startTime	string	YYYY-MM-DDThh:mm:ss.0000000+hh:mm	x	Start time for pushing positions to tour
vehicle.telematicData.endTime	string	YYYY-MM-DDThh:mm:ss.0000000+hh:mm		End time for stopping push positions to tour
drivers	array			array of drivers. Drive&Arrive currently supports only one driver element.
drivers[j].driverDescription	string			driver description
drivers[j].useRaSTime	boolean			consider break and rest in ETA calculations
drivers[j].raSTime	object			break and rest details
drivers[j].periodDrivenSinceLastBreak	integer			amount of time the driver has spent operating his vehicle since the last break (in seconds)
drivers[j].periodDrivenSinceLastRest	integer			amount of time the driver has spent operating his vehicle since the last rest (in seconds)
drivers[j].currentIdlePeriod	integer			amount of time the driver has spent idle right before the reference time (in seconds)
drivers[j].isSplitBreak	boolean			True if the driver has already completed the first part of his split break. Since then he has operated his vehicle or performed active service.
drivers[j].isSplitRest	boolean			True if the driver has already completed the first part of his split rest. Since then he has operated his vehicle or performed active service.
drivers[j].customData	object			custom json object related to driver
customData	object			a JSON object with arbitrary data
options.plannedTourStartTime	string	YYYY-MM-DDThh:mm:ss.0000000+hh:mm		Planned tour start date and time
options.doRefRouteCalc	boolean			True if a reference ETA is required for the tour. Stop 1 being the start point.

The example deletes a stop (stop is not transmitted anymore), updates one of the existing stops (scemid for stop specified) and adds a new one (no scemid for stop specified).

{
  "tours": [{
    "stops": [
      {
        "coordinate": {
          "locationX": 9.000000,
          "locationY": 49.000000
        },
        "earliestArrivalTime": "YYYY-MM-DDThh:mm:ss.0000000+01:00",
        "latestDepartureTime": "YYYY-MM-DDThh:mm:ss.0000000+01:00",
        "pta": "YYYY-MM-DDThh:mm:ss.0000000+01:00",
        "serviceTimeAtStop": 900,
        "useServicePeriodForRecreation": true,
        "weightWhenLeavingStop": 3000,
        "scemid": "X2X2X2X2X2",
      },
      {
        "coordinate": {
          "locationX": 8.000000,
          "locationY": 49.000000
        },
        "earliestArrivalTime": "YYYY-MM-DDThh:mm:ss.0000000+01:00",
        "latestDepartureTime": "YYYY-MM-DDThh:mm:ss.0000000+01:00",
        "pta": "YYYY-MM-DDThh:mm:ss.0000000+01:00",
        "serviceTimeAtStop": 0,
        "useServicePeriodForRecreation": true,
        "weightWhenLeavingStop": 0,
        "customData": {
          "orderId": "23534579"
        }
      }
    ],
    "vehicle": {
      "vehicleProfileID": "mg-truck-40t"
    },
    "drivers": [
      {
        "driverDescription": "driver 1",
        "raSTime": {
          "periodDrivenSinceLastBreak": 0,
          "periodDrivenSinceLastRest": 0,
          "currentIdlePeriod": 0,
          "isSplitBreak": false,
          "isSplitRest": false
        }
      }
    ],
    "customData": {
      "tripId": "example_0001"
    },
    "scemid": "X9X9X9X9X9"
  }]
}

Result

{
  "tours": [
    {
      "stops": [
        {
          "coordinate": {
            "locationX": 9.000000,
            "locationY": 49.000000
          },
          "earliestArrivalTime": "YYYY-MM-DDThh:mm:ss.0000000+01:00",
          "latestDepartureTime": "YYYY-MM-DDThh:mm:ss.0000000+01:00",
          "pta": "YYYY-MM-DDThh:mm:ss.0000000+01:00",
          "serviceTimeAtStop": 900,
          "useServicePeriodForRecreation": true,
          "weightWhenLeavingStop": 3000,
          "scemid": "X2X2X2X2X2"
        },
        {
          "coordinate": {
            "locationX": 8.000000,
            "locationY": 49.000000
          },
          "earliestArrivalTime": "YYYY-MM-DDThh:mm:ss.0000000+01:00",
          "latestDepartureTime": "YYYY-MM-DDThh:mm:ss.0000000+01:00",
          "pta": "YYYY-MM-DDThh:mm:ss.0000000+01:00",
          "serviceTimeAtStop": 0,
          "useServicePeriodForRecreation": true,
          "weightWhenLeavingStop": 0,
          "customData": {
            "orderId": "23534579"
          },
          "scemid": "X3X3X3X3X3"
        }
      ],
      "vehicle": {
        "vehicleProfileID": "mg-truck-40t"
      },
      "drivers": [
        {
          "driverDescription": "driver 1",
          "raSTime": {
            "periodDrivenSinceLastBreak": 1200,
            "periodDrivenSinceLastRest": 1200,
            "currentIdlePeriod": 0,
            "isSplitBreak": false,
            "isSplitRest": false
          }, 
          "useRaSTime": true
        }
      ],
      "customData": {
        "tripId": "example_0001"
      },
      "scemid": "X9X9X9X9X9"
    }
  ],
  "responseStatus": {
    "errorCode": "SUCCESS",
    "message": "00000000000000000000000000000000"
  }
}

All subscriptions of missing stops of the updated tour will be removed automatically.

Changing tour connect properties

Existing tour connect to a telematics provider can be updated using this API. If no tour connect object is provided in the update tour, the existing tour connect object will be removed.

Changing stops in tour

Updating stops will update ETA to the earliest arrival time for that stop.

Changing stops order will keep the last status related to that stop.

Removing stops will remove ETA-schedules related to that stop.

Exceptions

validation / message	errorCode
latestDepartureTime of stop before earliestArrivalTime	TIME_OF_STOP_INVALID
earliestArrivalTime of stop invalid or latestDepartureTime of stop invalid	TIME_OF_STOP_MISSING
Token does not exist	TOKEN_ERROR
SCEM-ID not valid. SCEM-ID should be a 10-digit, case-sensitive, alphanumeric identifier of an existing tour.	SCEMID_INVALID
Only update of a single tour is currently supported.	INVALID_TOUR_COUNT
In a tour with 2 stops, the stop coordinates needs to be different.	2_STOP_TOUR_REQUIRES_DIFF_COORDINATES
Tour start cannot be N days in the future. [START_DATE]	INVALID_TOUR_START_DATETIME
Maximum allowed tour duration of N days from [TOUR_DURATION] has been exceeded.	TOUR_DURATION_EXCEEDED
Tour update quota has been reached. Please try again later.	TOUR_UPDATE_QUOTA_FULL

Start time and tour duration

For these parameters a default of 7 days is used, but it is possible to customize these limits per call which is identified via access token.

Calling limitations

In order to prevent misuse of tour change requests by bypassing new tours with https://driveandarrive-v1.cloud.ptvgroup.com/em/tour/ POST, Drive&Arrive imposes following limitation on tour update calls: maximum of 200 tour or stops updates can be made in 24 hours interval.

This limitation can be configured as desired and set per token. If you need more quota for tour update requests, please contact our support.

/tour/batch/telematic/_PUT - Update tour telematics data

This interface is used to update tour telematics data in tour.vehicle using tour scemid(s). Multiple tours scemid is allowed with this update process.

Request PUT

https://driveandarrive-v1.cloud.ptvgroup.com/em/tour/batch/telematic/?Scemids=<SCEMID1>%2C<SCEMID2>&Token=<token>&Source=my_appVx.y

Request body

{
  "TelematicData": {
    "Provider":  "<position provider>",           // optional
    "VehicleId": "<vehicle reference>",           // mandatory
    "StartTime": "YYYY-MM-DDThh:mm:ss.000+00:00", // mandatory
    "EndTime":   "YYYY-MM-DDThh:mm:ss.000+00:00"  // optional
  }
}

Response (Success 200)

{
  "responseStatus": {
    "errorCode": "SUCCESS",
    "message": "349161fb-a4e2-47a1-9553-a94900b9ade7"
  }
}

Response

On error, a 400 response is returned with a belonging error message.

validation / message	errorCode
SCEM-ID not valid. SCEM-ID should be a 10-digit, case-sensitive, alphanumeric identifier of an existing tour.	SCEMID_INVALID
Vehicle Id is required for telematics.	TELEMATIC_VEHICLEID_REQUIRED
Start time for telematics positions is required.	TELEMATIC_STARTTIME_REQUIRED
TelematicData should not be empty.	NotNull
SCEMIDS should not be empty.	NotNull

/tour/batch/ DELETE - delete multiple tours which belong to the specified SCEM-IDs

The call to https://driveandarrive-v1.cloud.ptvgroup.com/em/tour/batch?token=<token>&SCEMIDS=<SCEMID1, SCEMID2, ...> &source=<myProduct_Vx.y> will delete multiple tours of a token.

Result

{
  "responseStatus": {
    "errorCode": "SUCCESS",
    "message": "000000000000"
  }
}

When deleting a tour, all subscriptions to this tour will be removed automatically.

Exceptions

validation / message	errorCode
Token does not exist.	TOKEN_ERROR
SCEM-ID not valid. SCEM-ID should be a 10-digit, case-sensitive, alphanumeric identifier of an existing tour.	SCEMID_INVALID
Deleting of multiple tours is not allowed.	ERR_MESSAGE_INVALID_DELETE_TOUR_COUNT

EXPERIMENTAL /tour/vehicle/profile - PUT - Update tour vehicle profile using custom search and location Id.

To update vehicle profile for an already existing tour call https://driveandarrive-v1.cloud.ptvgroup.com/em/tour/vehicle/profile?token=<token>&locationId=<locationId>&vehicleProfileID=<new-vehicle-profile>&source=<myProduct_Vx.y>.

A searchFieldContent in body is required. The searchFieldContent contains searchFields.fieldName and searchFields.fieldValue, to search for the stop to locationId provided. If the search returns a single result and the profile exists in the location token, then the vehicle profile is updated. Else a respective error with message is returned in response.

A journal entry is written on vehicle profile update. A reference route calculation will be triggered, if a change occurs in the vehicle profile.

Example: https://driveandarrive-v1.cloud.ptvgroup.com/em/tour/vehicle/profile?token=tokenXXXXXXXXXXXXXXXXXXXX&locationId=locationIdXXXXXXXXXXXXX&vehicleProfileID=newProfile&source=test

{
  "SearchFieldContent": {
    "SearchFields": [
      {
        {
          "fieldName": "customId",
          "fieldValue": "01234567"
        },
        {
          "fieldName": "pin",
          "fieldValue": "0123"
        }
      }
    ]
  }
}
}

Result

Success if vehicle profile has been changed. A corresponding error message with error code if the profile could not be changed. See Error responses for detailed error messages.

Exceptions

validation / message	errorCode
LocationID should not be empty.	NotNull
VehicleProfileID should not be empty.	NotNull
SearchFieldContent should not be empty.	NotNull
Could not update vehicle profile.	VEHICLE_PROFILE_UPDATE_FAILED
Could not update vehicle profile. Search result was empty or not unique (Count=x).	VEHICLE_PROFILE_UPDATE_FAILED
SearchFields is missing or empty.	SEARCH_FIELD_CONTENT_INVALID
Location-ID not valid. Location should be a 25-digit, case-sensitive, alphanumeric identifier of a location.	LOCATION_ID_INVALID
The location does not exist (for this token).	LOCATION_ERROR
Token does not exist.	TOKEN_ERROR
Profile not existing. You should use one of the predefined profiles.	NO_SUCH_VEHICLEPROFILE

Tour using tags (in an EXPERIMENTAL stage)

Tags are used to mark specified tours. The naming is free, but they are always converted to UPPERCASE and stored without trailing blanks (for each request)

This functionality could only be used from the Tour owner.

EXPERIMENTAL /tour/tags/{SCEMID} - POST - Add tags to a specified tour

Request

Please remember all tags are converted to upper.

https://driveandarrive-v1.cloud.ptvgroup.com/em/tour/tags/SCEMIDYYYY?Tags=TEST4,AcciDENT&Token=tokenXXXXXXXXXXXXXXXXXXXX

Successful result

Please remember all tags are returned, including the already existing ones.

{
	"scemid": "SCEMIDYYYY",
	"tags": [
		"TEST5",
		"TEST4",
		"ACCIDENT"
	],
	"responseStatus": {
		"errorCode": "SUCCESS",
		"message": "0b8644643e5749dbb474a6ea006a8165"
	}
}

Error response

{
	"scemid": "SCEMIDXXXX",
	"responseStatus": {
		"errorCode": "SCEMID_INVALID",
		"message": "SCEM-ID not valid. SCEM-ID should be a 10-digit, case-sensitive, alphanumeric identifier of an existing tour.|63fef29c783246df91c6a6ea00699c28"
	}
}

EXPERIMENTAL /tour/tags/{SCEMID} - DELETE - Delete tags from a specified tour

Request

https://driveandarrive-v1.cloud.ptvgroup.com/em/tour/tags/SCEMIDYYYY?Tags=TEST1,ACCIDENTS&Token=tokenXXXXXXXXXXXXXXXXXXXX

Successful result

All still existing tags are returned

{
	"scemid": "SCEMIDYYYY",
	"tags": [
		"TEST5",
		"TEST4",
		"ACCIDENT"
	],
	"responseStatus": {
		"errorCode": "SUCCESS",
		"message": "0b8644643e5749dbb474a6ea006a8165"
	}
}

Error response

{
	"scemid": "SCEMIDXXXX",
	"responseStatus": {
		"errorCode": "SCEMID_INVALID",
		"message": "SCEM-ID not valid. SCEM-ID should be a 10-digit, case-sensitive, alphanumeric identifier of an existing tour.|63fef29c783246df91c6a6ea00699c28"
	}
}

EXPERIMENTAL /tour/tags/{SCEMID} - GET - Get the tags of a specified tour

There are two possibilities to get the tags assigned to a tour. The first query the tour and search for Tour.Tags or use this method with mandatory Token and Tour.SCEMID

Request

https://driveandarrive-v1.cloud.ptvgroup.com/em/tour/tags/SCEMIDXXXX?Token=tokenXXXXXXXXXXXXXXXXXXXX

Successful result. Tag=TEST5 assigned

{
	"tags": 
	[
		"TEST5"
	],
	"scemid": "SCEMIDXXXX",
	"responseStatus": {
		"errorCode": "SUCCESS",
		"message": "db168fead2ce425183c0a6ea00674a8f"
	}
}

Error response

{
	"scemid": "SCEMIDxxxxx",
	"responseStatus": {
		"errorCode": "SCEMID_INVALID",
		"message": "SCEM-ID not valid. SCEM-ID should be a 10-digit, case-sensitive, alphanumeric identifier of an existing tour.|63fef29c783246df91c6a6ea00699c28"
	}
}

EXPERIMENTAL /tour/taggedtours/ - GET - Get tours with the specified tags

The parameters from and until are not implemented yet. If the parameter AddTourData=true, tour infomation is returned in the parameter foundTours

Request


https://driveandarrive-v1.cloud.ptvgroup.com/em/tour/taggedtours/?Tags=UNFALL&MaxItemCount=12&&&AddTourData=false&Token=PTV_jmeter_8PS6F868QDPW4I&

Successful result. AddTourData=false

{
	"requestedTags": [
		"UNFALL"
	],
	"tourSCEMIDs": [
		"AAAAAAAAAA",
		"BBBBBBBBBB",
		"CCCCCCCCCC"
	],
	"searchCriteria": {
		"maxItemCount": 12,
		"from": "0001-01-01T00:00:00.0000000+00:00",
		"until": "0001-01-01T00:00:00.0000000+00:00",
		"addTourData": false
	},
	"responseStatus": {
		"errorCode": "SUCCESS",
		"message": "a6b7793f7fe8423386b5a6e900cdb247"
		}
}

Error response

{
	"requestedTags": [
		"ACCIDENTIAL"
	],
	"searchCriteria": {
		"maxItemCount": 12,
		"from": "0001-01-01T00:00:00.0000000+00:00",
		"until": "0001-01-01T00:00:00.0000000+00:00",
		"addTourData": true
	},
	"responseStatus": {
		"errorCode": "SCEMID_INVALID",
		"message": "SCEM-ID not valid. SCEM-ID should be a 10-digit, case-sensitive, alphanumeric identifier of an existing tour.|911f90229b5641d2a795a6ea00781f7c"
	}
}

EXPERIMENTAL /tour/tokentags/ - GET - Get the tags which are currently used for the specified token

This method is used to query all used tags.

Request

https://driveandarrive-v1.cloud.ptvgroup.com/em/tour/tokentags/?Token=tokenXXXXXXXXXXXXXXXXXXXX

Successful result

{
	"existingTags": [
		"31.12.2016",
		"BREAK 45",
		"BREAK_45",
		"SANTA",
		"TEST1",
		"TEST2",
		"TEST3",
		"TEST5",
		"UNFALL"
	],
	"responseStatus": {
		"errorCode": "SUCCESS",
		"message": "c22dc07cc4c94f50bcb8a6e900ca661e"
	}
}

Error response

{
	"responseStatus": {
		"errorCode": "TOKEN_ERROR",
		"message": "Token Tokenyyyyyyyyyyyyyyyyyyy does not exist.|4f0ccb7222584d7fa85ea6ea00739679",
		"errors": [
			{
				"errorCode": "TOKEN_ERROR",
				"fieldName": "Token",
				"message": "Token Tokenyyyyyyyyyyyyyyyyyyy does not exist.|4f0ccb7222584d7fa85ea6ea00739679",
				"meta": {
					"PropertyName": "Token"
				}
			}
		]
	}
}

Get in Contact